Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Device Functions / Manipulating View Device Object Properties

GXGetViewDeviceBitmap

You can use the GXGetViewDeviceBitmap function to retrieve the bitmap property of a view device object.

gxShape GXGetViewDeviceBitmap(gxViewDevice source);

source

A reference to the view device whose bitmap you wish to examine.

function result

A bitmap shape object that is a copy of the information in the view device's bitmap property.

DESCRIPTION

The GXGetViewDeviceBitmap function returns a bitmap shape that is a copy of the bitmap representing the imaging area of the specified device. The pixel image pointer in the bitmap structure of the bitmap shape may be nil if, for example, the image is on disk. The pointer is not nil if the image is associated with an onscreen device or was supplied by an application.

The shape returned by this function is a copy of the device's bitmap, so if you alter it you must reassign it to the view device with the GXSetViewDeviceBitmap function. However, the pixel image of the bitmap shape returned by this function is not a copy; it is the same pixel image as that used by the view device. Thus if you draw to the view device you modify the pixel image of the returned shape, and likewise if you modify the pixel image of the returned shape you modify the pixel image of the view device. You can take advantage of this fact to draw an offscreen bitmap directly to an onscreen view device.

SPECIAL CONSIDERATIONS

If no error occurs, the GXGetViewDeviceBitmap function creates a shape object; you are responsible for disposing of that object when you no longer need it.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
invalid_viewDevice_reference

SEE ALSO

For examples of the use of this function, see page 7-55 and Listing 7-14 on page 7-63.

To set a view devices's bitmap property, use the GXSetViewDeviceBitmap function, described next.

For information about bitmap shapes, the bitmap structure, and pixel images, see the bitmap shapes chapter of Inside Macintosh: QuickDraw GX Graphics.